Celestin Apprentice 7

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / PowerPlant / HCmdButtonAttachment 1.1.1 / HCmdButtonAttachment README next >

Wrap

Text File | 1997-07-20 | 13.6 KB | 303 lines | [TEXT/CWIE]

/*******************************************************************************\ | | | HCmdButtonAttachment ©1997 John C. Daub. All rights reserved. | | | | John C. Daub <mailto:hsoi@eden.com> | | <http://www.eden.com/~hsoi/> <http://www.eden.com/~hsoi/prog.html> | | | \*******************************************************************************/ DESCRIPTION ``````````` A Metrowerks PowerPlant® inherited class that gives controls (LControls) a command-key equivalent. This allows for more keyboard navigation. For example, the traditional "Save before closing?" dialog asks to "Save", "Cancel" or "Don't Save". Save is typically the default key (return) and Cancel the cancel (escape), but there is no keyboard way to hit Don't Save. Enter HCmdButtonAttachment. With HCmdButtonAttachment, you can give (almost) any LControl a command-key shortcut. You can specify the key to be the first letter/character of the control's descriptor or it can be a character of your own arbitrary specification. You can also have the title of the control change to display the shortcut or not, and do so after a user-configurable amount of time. This archive includes the HCmdButtonAttachment sources, a custom CTYP file for use with Constructor 2.4 or later, and an example application to demonstrate the class. HOW TO USE HCmdButtonAttachment ``````````````````````````````` Using this class is fairly easy. Let's go over a few things: - To make life easier, put the CTYP file (or an alias to it) in the specified location to allow Constructor to read in the CTYP at launch time. This will make editing in Constructor easier. - Launch Constructor and open the sample app's .ppob file. Open either of the 'PPob' resources, Show Hierarchy (as this is the only way to view attachments) and then open a Property Inspector window for any of the available HCmdButtonAttachments. Let's explain the fields: Control's PaneID - the PaneIDT of the control on which we are to act Use Specified Key - true = use the specified key false = use the first character of the control descriptor Specified Key - the specified key to use (ignored if "Use Specified Key" is false). Even if "Use Specified Key" is false, you MUST fill in something for this value else the LStream ctor can fail. Delay - amount of time (in ticks) before we would draw the keyboard shortcut in the control title/descriptor Draw Shortcut - do you wish the shortcut to be drawn in the title or not? I have attempted to demonstrate the variances and purposes of these fields throughout the demo. Examine the demo's 'PPob's more in-depth to see all of the variations. - It is important to remember how attachments work in PowerPlant. An attachment attaches to an LCommander. Most of your controls are NOT commanders, so this attachment actually attaches to the closest supercommander. e.g. in our example, we attach to the LWindow or the LGADialogBox that contains the controls. You can see how this impacts behavior by again remembering how attachments work in PowerPlant, as well as looking at HCmdButtonAttachment::InitCmdButtonAttachment(). - Tho this class inherits from both LAttachment and LPeriodical, the class is an attachment for all practical purposes. It just happens to also repeat. This is a necessary oddity so the drawing of the shortcut can take place. - The default behavior for drawing the shortcut goes from "Fred" to "Fred cmd-F" (but the cmd is actually the cloverleaf). You can customize this to your own liking by subclassing and overriding MungeTitle(). - To use this class doesn't take much more than registering the class (if you will be creating it from a stream), adding the source file to your project, and then instantiating the object. I've worked to make it as drop and play as possible. I have found it easiest to create the attachments in Constructor, but it is possible to create on the fly. I have demonstrated this in the example application. - When setting the Execute Message of the attachment, be sure to set it to msg_KeyPress (814 in PP_Messages.h). First, this is the message that this attachment is to execute upon. Also, as of this writing, Constructor (2.4.1) could not display this message in it's popup menu in the Property Inspector window. You will have to enter "814" yourself. This should be remedied in Constructor 2.4.2 (part of CodeWarrior Pro 1) - You can have duplicate "hot keys" for the controls... one control could be cmd-F and another also be cmd-F. But note that when cmd-F is pressed, both of these controls will execute. Depending what you want, that may or may not be desired behavior. (and there really isn't a clean way that I can see to work around this issue, aside from just paying attention to what you're programming). - Be sure when designing your controls that if you have the shortcut drawn, that your control will be wide enough to accomidate the larger/longer text string. - If you wish to use this attachment with a control that doesn't have a descriptor (e.g. an icon control like LGAIconButton), be sure to specify a key to use and to NOT draw the shortcut. - Hopefully the rest should be pretty self-explanatory between reading this, the source itself, and then the demo. CREDITS ``````` I wrote this because well...I wanted to have something that would do this :) I've seen others do this sort of thing, and they are good implementations, just not what I wanted for my needs. I would like to thank Greg Bolsinga for allowing me to pick his brain at odd times while he tried to get work done, as well as seeing his own version of something like this. DISCLAIMER `````````` This is NOT a product of Metrowerks Corporation. Please do NOT contact Metrowerks for help/support of this class/code. If you need support, please use the contact information given below. LICENSING AND USAGE AGREEMENT ````````````````````````````` John C. Daub (author) grants you, and you accept, a nonexclusive, nontransferable license to distribute this code for you within your programs and projects. You may distribute this code in object code form only and only on magnetic diskettes, CD-ROM, or other media with your programs into which this code has been incorporated (if you need to distribute your program by some other medium, please contact the author). You agree that this license gives you no title nor rights of ownership in, of, and/or to this code, and acknowledge that this code is property of John C. Daub. This code is NOT in the public domain. Permission is granted to the following organizations to distribute this code on their CD-ROM collections: Pacific HiTech, Inc - Info-Mac CD-ROM Celestin Company - Apprentice CD Meterowerks Corporation - CodeWarrior If you and/or your organization wishes to distribute this code and are not explicitly listed above, please contact John C. Daub. You may modify the source code, compile it, and incorporate the resulting object code into your programs. If you modify the code, you cannot redistribute the modified code under the same class/code name. Furthermore, to prevent any problems and/or infringements, please contact the author prior to redistribution of any modified code. John C. Daub licenses this code to you on an "AS IS" basis. John C. Daub makes no warranties, neither expressed nor implied, regarding this code, its merchantability, nor its fitness for any purpose. John C. Daub agrees to make a reasonable effort to provide written or verbal corrections for any problems that might be found in this code. Use of this code must be credited in an appropriate manner and location (such as printed or online documentation and/or About boxes) with the following credit line: HCmdButtonAttachment ©1997 John C. Daub. All rights reserved. If this license is too restrictive with the current law in your state or country, you should not use this code at all. Furthermore, if you personally find this agreement too restrictive or not to your satisfaction, you should not use this code at all. FUTURE `````` - v1.1 should allow other alpha-numeric characters to be used (e.g. = , . ). However, unprintable characters (e.g. <enter> <Esc>) still cannot be displayed. I'd like to see if I could come up with a technique to allow any "legal" keys to be used (kinda like the Mercutio MDEF does). - Allow more modifier keys to be specified, i.e. shift, option, control (maybe caps lock?), if desired. - Currently the attachment looks to see if command is held down... doesn't care about any others. If you have cmd, fine. If you have shift, no go. But if you have cmd and shift, it will still work. I don't know if this is something that I'd want to limit or not (i.e use this key and only this key). As things stand now, it probably doesn't matter. But of course if I do allow other key combos, it will have to be an "if and only if" situation. The Finder does allow for this (e.g. cmd-F and cmd-shift-F are the same thing) and that makes sense since one could interpret cmd-F to really be cmd-f, and that cmd-F implies the need for shift (to make the caps). So it makes sense and all that. And I can't rememeber exactly, but something tells me that a future MacOS version (maybe Rhapsody?) will be case sensative. So cmd-F and cmd-f will actually be different (and cmd-F will imply shift, and cmd-shift-f is the same thing). Have to wait and see.... - The class can only be used with controls that have text titles/descriptors. Controls that are icons don't really work that well here. You can do it (just be sure to specify to NOT draw the shortcut). But it might be nice to have some sort of mechanism to show the shortcut on non-text controls... just a matter of how to accomplish this. - One shortcoming is that we draw the command key based upon the given font. Very few fonts from what I've seen actually map char_Propeller (0x11) to a printable "cloverleaf". Most either implement nothing (e.g. that empty box) or implement something that is nothing (e.g. just is blank). Chicago has it, Truth has it... but things like Geneva don't have it. So this limits the class by forcing you to use a font like Chicago or preferably the "System" font... but not everyone wants to do that. That's part of the reason why I broke the title munging routine out for easy modification..... But I just don't know what would be an adequate way to get around this (aside from telling font authors to implement the full character suite).... and I would like to avoid a Window-ish underlining of the given character. Typically you can work around this by not drawing the shortcut... just let the command be there (e.g. by first letter of the button text or some such) CONTACT INFORMATION ``````````````````` Even though you don't need to send me email or register or anything to use the code, it would still be nice to drop me a line and let me know what you think. If you find any bugs or add any cool features, send them to me so I can add it to the official distribution. Furthermore, if I have your contact information, I can notify you when new versions are released -- can be very handy if say there is a fatal crashing bug in the code or some such. So, it's probably in your own best interest to drop me a line :-) Also, be sure to visit my web site <http://www.eden.com/~hsoi/prog.html> and "register". I won't know if you're "registered" or not, but it's a nice way that you can be notified of product updates (e.g. I make a new version, post it on that page, if you're registered, you'll be emailed automatically that the page changed). John C. Daub <mailto:hsoi@eden.com> <http://www.eden.com/~hsoi/prog.html> CHANGE HISTORY `````````````` Date Vers Who Notes ---------------------------------------------------------------------------- 22 Apr 97 1.0 JCD - Created and initial release 24 Jun 97 1.1 JCD - Removed the hyphen from MungeTitle(). Makes the shortcut look the same as in MENUs and such. - Restructured class declaration (ordering of data members) (I heard struct alignment affects classes as well...) - FindHotKey() only calls UppercaseText() if theHotKey is between 'a' and 'z'...saves a bit of a call, and should also allow non-alphanumeric keys to be used - Updated licensing agreement. - Upgraded to CW Pro1. - Can compile with no precompiled headers now. - Cleaned up sources for improved readability. 15 Jul 97 1.1.1 JCD - All ctor's use initialization lists instead of assignment (where possible). - All member data is now private (was protected). Appropriate accessor functions have been created (as public or protected, depending on context). Helps to further abstract the user away from the data (good C++ style). - Added include for PowerPlant_PCH to be consistant with PowerPlant sources. - Inline functions no longer defined within class declaration. Definitions moved outside of the class, but still in the header file. #pragma mark's added to source file to ease navigation and user indexing. - In SpendTime() the call to FindHotKey moved from outside the if-else statement to inside the statement just before MungeTitle is called (saves calling this routine if not needed, e.g. the else-statement). - In InitCmdButtonAttachment, we got the control's original title. If we failed, mOriginalTitle was assigned a nil string. But this is unnecessary as mOrignialTitle is set to nil in the ctor's and not otherwise modified. Saves a decent amount of code-gen size. - Demo's GA dialog now has attachments for Cancel and OK buttons.